package ch.jamme;

import ch.jamme.conf.*;

/**
 * This is the main interface of this project.
 * It basically reflects the purposes of the project itself by allowing to transform an object
 * (or more precisely a graph of objects) in its XML representation and conversely to transorm
 * an XML String back in the graph of objects from where the XML has been generated.
 * @author Mario Fusco
 */
public interface Marshaller {
	
	/**
	 * Marshall an Object in its XML representation
	 * @param source The source object to be marshalled
	 * @return The String containing the XML resulting from the marshall process
	 */
	String marshall(Object source);

	/**
	 * Marshall an Object in its XML representation using the given configuration.
	 * @param source The source object to be marshalled
	 * @param configuration The configuration used to marshall the given object
	 * @return The String containing the XML resulting from the marshall process
	 */
	String marshall(Object source, MarshallerConfiguration configuration);
	
	/**
	 * Unmarshall an XML String transforming it in the graph of objects that it represents
	 * @param xml The String to be unmarshalled
	 * @return The Object resulting from the unmarshall process
	 */
	Object unmarshall(String xml);

	/**
	 * Unmarshall an XML String transforming it in the graph of objects that it represents
	 * having as a root an object of the given class
	 * @param xml The String to be unmarshalled
	 * @param rootClass The class of the object resulting from the xml unmarshall
	 * @return The Object resulting from the unmarshall process
	 */
	<T> T unmarshall(String xml, Class<T> rootClass);
	
	/**
	 * Unmarshall an XML String transforming it in the graph of objects that it represents using the given configuration.
	 * @param xml The String to be unmarshalled
	 * @param configuration The configuration used to unmarshall the given xml string
	 * @return The Object resulting from the unmarshall process
	 */
	Object unmarshall(String xml, MarshallerConfiguration configuration);
	
	/**
	 * Unmarshall an XML String transforming it in the graph of objects that it represents
	 * having as a root an object of the given class using the given configuration.
	 * @param xml The String to be unmarshalled
	 * @param rootClass The class of the object resulting from the xml unmarshall
	 * @param configuration The configuration used to unmarshall the given xml string
	 * @return The Object resulting from the unmarshall process
	 */
	<T> T unmarshall(String xml, Class<T> rootClass, MarshallerConfiguration configuration);

	/**
	 * Returns the default configuration used by this marshaller.
	 * The returned configuration object is a clone of the actual one, so it can be safely modified
	 * and used in a specific marshall process without changing the standard marshaller behavior.
	 */
	MarshallerConfiguration getConfiguration();
}
